<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
    <title>JavaScripTools Manual</title>
    <link rel="stylesheet" type="text/css" href="../../css/style.css">
</head>

<body>
<br>
<h1>JavaScripTools Manual</h1>
<h2>JavaScripTable</h2>
<h3>Using objects and exporting data</h3>
<p>The table is useful where you want the user to edit "child records", or edit multiple data
at a time.</p>
<p>The question is: how to retrieve the data after the edition? There are 3 ways:<ul>
<li>Setting the <code>selectionName</code> and the <code>name</code> for each EditControl. So,
when the form is submitted, the values may be retrieved at server side.</li>
<li>Encoding data into a single string using the <code>encode</code> method. More details ahead.</li>
<li>Retrieving the rows as objects using an <code>ObjectRowMapper</code>. Details ahead.</li>
</ul></p>
<br><br>
<a name="encoding"></a>
<h4>Encoding data into a single string</h4>
<p>This is done by the <code>encode</code> method. It takes three optional parameters: The rows to encode (you may use,
for example, the <code>getSelectedRows</code> method) - defaults to all rows, the columns (as a number array) - defaults to all,
and a flag, indicating if the row identifier should be encoded or not - defaults to true.</p>
<p>A <a href="Parsers_intro.html">Parser</a> is used for each column. It may be set a explicit parser using the column
<code>encodingParser</code> property, or may by used a default parser according to the data type. The table has the following properties as default
parsers (the default values are in parenthesis): <code>stringEncodingParser</code> (JST_DEFAULT_STRING_ENCODING_PARSER),
<code>numberEncodingParser</code> (JST_DEFAULT_NUMBER_ENCODING_PARSER), <code>currencyEncodingParser</code> (JST_DEFAULT_CURRENCY_ENCODING_PARSER),
<code>dateEncodingParser</code> (JST_DEFAULT_DATE_ENCODING_PARSER) and <code>booleanEncodingParser</code> (JST_DEFAULT_BOOLEAN_ENCODING_PARSER).</p>
<p>A separator is used between values (a single cell may contain multiple values) - <code>valueSeparator</code> (JST_DEFAULT_VALUE_SEPARATOR), 
between columns - <code>columnSeparator</code> (JST_DEFAULT_COLUMN_SEPARATOR) and between rows - <code>rowSeparator</code> (JST_DEFAULT_ROW_SEPARATOR).</p>
<p>Here is a brief example:</p>
<pre>var table = new JavaScripTable(...);
var col;
table.addColumn(new Column("Name", JST_TYPE_STRING));
table.addColumn(new Column("Age", JST_TYPE_NUMBER));
table.addColumn(new Column("Married", JST_TYPE_BOOLEAN));
table.addRow(1, ["John", 38, true]);
table.addRow(2, ["Mary", 27, false]);
table.rowSeparator = "\n";
table.columnSeparator = ";";
table.encode(); -> "John;38;true\nMary;27;false";
</pre>
<br><br>
<a name="objects"></a>
<h4>Using an ObjectRowMapper</h4>
<p>An <a href="../api/class_ObjectRowMapper.html">ObjectRowMapper</a> is a class that converts objects to rows and rows to objects.</p>
<p>There are 2 ways of setting an ObjectRowMapper: setting the table <code>identifierName</code> and each column <code>propertyName</code> 
properties, so an ObjectRowMapper will be created by the table, or manually setting the ObjectRowMapper instance. For example:</p>
<pre>function Customer(id, name, age, married) {
    this.customerId = id;
    this.name = name;
    this.age = age;
    this.isMarried = married;
}
var table = ...; //Assume the same table as the encoding example

//First way: Using an implicit ObjectRowMapper
table.identifierName = "customerId";
//The propertyName could be assigned to the Column instance that is returned by addColumn
table.getColumnByIndex(0).propertyName = "name";
table.getColumnByIndex(1).propertyName = "age";
table.getColumnByIndex(2).propertyName = "isMarried";

//Second way: Using an explicit ObjectRowMapper
table.objectRowMapper = new ObjectRowMapper();
table.objectRowMapper.className = "Customer";
table.objectRowMapper.mapIdentifier("customerId");
table.objectRowMapper.mapProperty(0, "name");
table.objectRowMapper.mapProperty(1, "age");
table.objectRowMapper.mapProperty(2, "isMarried");

//Now you can retrieve rows as objects, or add rows as objects
table.getAllRowsAsObjects(); -> Returns 2 Customer instances
table.addRow(new Customer(3, "Peter", 68, true));
table.updateRow(new Customer(1, "John", 40, true));
</pre>
<p>If you are a Java developer and use Ajax, you could try, for example, to work with <a href="http://getahead.ltd.uk/dwr">DWR</a>
(Direct Web Remoting), that allows you to pass JavaScript objects direct to Java. In this case, using an ObjectRowMapper is very useful.</p>
<br><br>
<hr>
<table width="100%">
    <tr>
        <td width="33%" align="left"><b>Previous:</b><br><a href="JavaScripTable_interaction.html">User interaction</a></td>
        <td width="34%" align="center"><a href="index.html">Table of Contents</a></td>
        <td width="33%" align="right"></td>
    </tr>
</table>

</body>
</html>
